@piwikpro/tracking-base-library
Advanced tools
Piwik PRO basic tracking library for the frontend.
Dedicated Piwik PRO library that helps with implementing Piwik PRO Tag Manager and the Piwik PRO tracking client in JavaScript browser applications.
To use this package in your project, run the following command.
npm install @piwikpro/tracking-base-library
In your project, include the default PiwikPro in the highest level application module. ie index. To set up the Piwik PRO Tag Manager container in the app, the easiest way is to call the PiwikPro. initialize() method. PiwikPro.initialize() must be initialized using this function before any of the other tracking functions will record any data.
In the arguments, pass your app ID and your account URL as parameters (marked 'container-id' and 'container-url' in the example below).
import PiwikPro from '@piwikpro/tracking-base-library';
PiwikPro.initialize('container-id', 'container-url');
The nonce attribute is useful to allow-list specific elements, such as a particular inline script or style elements. It can help you to avoid using the CSP unsafe-inline directive, which would allow-list all inline scripts or styles.
If you want your nonce to be passed to the script, pass it as an option to the third argument when calling the script initialization method.
import PiwikPro from '@piwikpro/tracking-base-library';
PiwikPro.initialize('container-id', 'container-url', { nonce: 'nonce-string' });
import PiwikPro from '@piwikpro/tracking-base-library';
PiwikPro.initialize('container-id', 'container-url', { dataLayerName: 'my-data-layer' });
import { PageViews, GoalConversions } from "@piwikpro/tracking-base-library"
PageViews.trackPageView();
GoalConversions.trackGoal(1, 100);
Ƭ Dimensions: Record<`dimension${number}`, string>
Ƭ InitOptions: Object
| Name | Type | Description |
|---|---|---|
dataLayerName? | string | Defaults to 'dataLayer' |
nonce? | string | - |
Ƭ PaymentInformation: Object
| Name | Type |
|---|---|
discount? | number | string |
grandTotal | number | string |
orderId | string |
shipping? | number | string |
subTotal? | number | string |
tax? | number | string |
Ƭ Product: Object
| Name | Type |
|---|---|
brand? | string |
category? | LimitedArrayFiveStrings |
customDimensions? | Record<number, string> |
name? | string |
price? | number |
quantity? | number |
sku | string |
variant? | string |
Ƭ VisitorInfo: [isNew: "0" | "1", visitorId: string, firstVisitTS: number, previousVisitCount: string | number, currentVisitTS: number, lastVisitTS: number | "", lastEcommerceOrderTS: number | ""]
• default: Object
| Name | Type |
|---|---|
getInitScript | (__namedParameters: { containerId: string ; containerUrl: string ; dataLayerName?: string }) => string |
initialize | (containerId: string, containerUrl: string, nonce?: string) => void(containerId: string, containerUrl: string, options?: InitOptions) => void |
▸ logAllContentBlocksOnPage(): void
Print all content blocks to the console for debugging purposes
void
services/content-tracking/contentTracking.service.ts:49
▸ trackAllContentImpressions(): void
Scans the entire DOM for content blocks and tracks impressions after all page elements load. It does not send duplicates on repeated calls unless trackPageView was called in between trackAllContentImpressions invocations
void
services/content-tracking/contentTracking.service.ts:9
▸ trackContentImpression(contentName, contentPiece, contentTarget): void
| Name | Type |
|---|---|
contentName | string |
contentPiece | string |
contentTarget | string |
void
services/content-tracking/contentTracking.service.ts:33
▸ trackContentImpressionsWithinNode(domNode): void
| Name | Type |
|---|---|
domNode | Node |
void
services/content-tracking/contentTracking.service.ts:29
▸ trackContentInteraction(contentInteraction, contentName, contentPiece, contentTarget): void
Tracks manual content interaction event
| Name | Type | Description |
|---|---|---|
contentInteraction | string | Type of interaction (e.g. "click") |
contentName | string | Name of a content block |
contentPiece | string | Name of the content that was displayed (e.g. link to an image) |
contentTarget | string | Where the content leads to (e.g. URL of some external website) |
void
services/content-tracking/contentTracking.service.ts:76
▸ trackContentInteractionNode(domNode, contentInteraction?): void
Tracks interaction with a block in domNode. Can be called from code placed in onclick attribute
| Name | Type | Default value | Description |
|---|---|---|---|
domNode | Node | undefined | Node marked as content block or containing content blocks. If content block can’t be found, nothing will tracked. |
contentInteraction | string | 'Unknown' | Name of interaction (e.g. "click") |
void
services/content-tracking/contentTracking.service.ts:58
▸ trackVisibleContentImpressions(checkOnScroll?, watchInterval?): void
Scans DOM for all visible content blocks and tracks impressions
| Name | Type | Default value | Description |
|---|---|---|---|
checkOnScroll | boolean | true | Whether to scan for visible content on scroll event |
watchInterval | number | 750 | Delay, in milliseconds, between scans for new visible content. Periodic checks can be disabled by passing 0 |
void
services/content-tracking/contentTracking.service.ts:18
▸ deleteCookies(): void
Deletes existing tracking cookies on the next page view
void
services/cookie-management/cookieManagement.service.ts:22
▸ disableCookies(): void
Disables all first party cookies. Existing cookies will be deleted in the next page view
void
services/cookie-management/cookieManagement.service.ts:8
▸ enableCookies(): void
Enables all first party cookies. Cookies will be created on the next tracking request
void
services/cookie-management/cookieManagement.service.ts:15
▸ getConfigVisitorCookieTimeout(): Promise<number>
Returns expiration time of visitor cookies (in milliseconds)
Promise<number>
services/cookie-management/cookieManagement.service.ts:86
▸ getCookieDomain(): Promise<string>
Returns domain of the analytics tracking cookies (set with setCookieDomain()).
Promise<string>
services/cookie-management/cookieManagement.service.ts:48
▸ getCookiePath(): Promise<string>
Returns the analytics tracking cookies path
Promise<string>
services/cookie-management/cookieManagement.service.ts:67
▸ getSessionCookieTimeout(): Promise<number>
Returns expiration time of session cookies
Promise<number>
services/cookie-management/cookieManagement.service.ts:112
▸ hasCookies(): Promise<boolean>
Returns true if cookies are enabled in this browser
Promise<boolean>
services/cookie-management/cookieManagement.service.ts:29
▸ setCookieDomain(domain): void
Sets the domain for the analytics tracking cookies
| Name | Type |
|---|---|
domain | string |
void
services/cookie-management/cookieManagement.service.ts:138
▸ setCookieNamePrefix(prefix): void
Sets the prefix for analytics tracking cookies. Default is "pk".
| Name | Type |
|---|---|
prefix | string |
void
services/cookie-management/cookieManagement.service.ts:131
▸ setCookiePath(path): void
Sets the analytics tracking cookies path
| Name | Type |
|---|---|
path | string |
void
services/cookie-management/cookieManagement.service.ts:145
▸ setReferralCookieTimeout(seconds): void
Sets the expiration time of referral cookies
| Name | Type |
|---|---|
seconds | number |
void
services/cookie-management/cookieManagement.service.ts:105
▸ setSecureCookie(secure): void
Toggles the secure cookie flag on all first party cookies (if you are using HTTPS)
| Name | Type |
|---|---|
secure | boolean |
void
services/cookie-management/cookieManagement.service.ts:152
▸ setSessionCookieTimeout(seconds): void
Sets the expiration time of session cookies
| Name | Type |
|---|---|
seconds | number |
void
services/cookie-management/cookieManagement.service.ts:166
▸ setVisitorCookieTimeout(seconds): void
Sets the expiration time of visitor cookies
| Name | Type |
|---|---|
seconds | number |
void
services/cookie-management/cookieManagement.service.ts:159
▸ setVisitorIdCookie(): void
Sets cookie containing analytics ID in browser
void
services/cookie-management/cookieManagement.service.ts:173
▸ deleteCustomDimension(customDimensionId): void
Removes a custom dimension with the specified ID.
| Name | Type |
|---|---|
customDimensionId | string | number |
void
services/custom-dimensions/customDimensions.service.ts:21
▸ getCustomDimensionValue(customDimensionId): Promise<string | undefined>
Returns the value of a custom dimension with the specified ID.
| Name | Type |
|---|---|
customDimensionId | string | number |
Promise<string | undefined>
services/custom-dimensions/customDimensions.service.ts:30
▸ setCustomDimensionValue(customDimensionId, customDimensionValue): void
Sets a custom dimension value to be used later.
| Name | Type |
|---|---|
customDimensionId | string | number |
customDimensionValue | string |
void
services/custom-dimensions/customDimensions.service.ts:8
▸ trackEvent(category, action, name?, value?, dimensions?): void
Tracks a custom event, e.g. when a visitor interacts with the page
| Name | Type |
|---|---|
category | string |
action | string |
name? | string |
value? | number |
dimensions? | Dimensions |
void
services/custom-events/customEvents.service.ts:8
Ƭ DataLayerEntry: Record<string, AnyData>
services/dataLayer/dataLayer.service.ts:11
▸ push(data): number
Adds entry to a data layer
| Name | Type |
|---|---|
data | DataLayerEntry |
number
services/dataLayer/dataLayer.service.ts:15
▸ setDataLayerName(name): void
| Name | Type |
|---|---|
name | string |
void
services/dataLayer/dataLayer.service.ts:7
▸ addDownloadExtensions(extensions): void
Adds new extensions to the download extensions list
| Name | Type |
|---|---|
extensions | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:61
▸ enableLinkTracking(trackAlsoMiddleAndRightClicks?): void
Enables automatic link tracking. If called with true, left, right and
middle clicks on links will be treated as opening a link. Opening a links to
an external site (different domain) creates an outlink event. Opening a link
to a downloadable file creates a download event
| Name | Type | Default value |
|---|---|---|
trackAlsoMiddleAndRightClicks | boolean | true |
void
services/download-and-outlink/download-and-outlink.service.ts:30
▸ getLinkTrackingTimer(): Promise<number>
Returns lock/wait time after a request set by setLinkTrackingTimer
Promise<number>
services/download-and-outlink/download-and-outlink.service.ts:89
▸ removeDownloadExtensions(extensions): void
Removes extensions from the download extensions list
| Name | Type |
|---|---|
extensions | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:68
▸ setDownloadClasses(classes): void
Sets a list of class names that indicate whether a list is a download and not an outlink
| Name | Type |
|---|---|
classes | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:47
▸ setDownloadExtensions(extensions): void
Overwrites the list of file extensions indicating that a link is a download
| Name | Type |
|---|---|
extensions | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:54
▸ setIgnoreClasses(classes): void
Set a list of class names that indicate a link should not be tracked
| Name | Type |
|---|---|
classes | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:108
▸ setLinkClasses(classes): void
Sets a list of class names that indicate whether a link is an outlink and not download
| Name | Type |
|---|---|
classes | string[] |
void
services/download-and-outlink/download-and-outlink.service.ts:40
▸ setLinkTrackingTimer(time): void
When a visitor produces an events and closes the page immediately afterwards, e.g. when opening a link, the request might get cancelled. To avoid loosing the last event this way, JavaScript Tracking Client will lock the page for a fraction of a second (if wait time hasn’t passed), giving the request time to reach the Collecting & Processing Pipeline
| Name | Type |
|---|---|
time | number |
void
services/download-and-outlink/download-and-outlink.service.ts:82
▸ trackLink(url, linkType, dimensions?, callback?): void
Manually tracks outlink or download event with provided values
| Name | Type |
|---|---|
url | string |
linkType | string |
dimensions? | Dimensions |
callback? | () => void |
void
services/download-and-outlink/download-and-outlink.service.ts:9
▸ enableJSErrorTracking(unique?): void
Enables tracking of unhandled JavaScript errors.
| Name | Type | Default value | Description |
|---|---|---|---|
unique | boolean | true | track only unique errors |
void
services/error-tracking/errorTracking.service.ts:8
▸ trackError(error): void
Attempts to send error tracking request using same format as native errors caught by enableJSErrorTracking(). Such error request will still follow rules set for tracker, so it will be sent only when JS error tracking is enabled (enableJSErrorTracking function was called before this attempt). It will also respect rules for tracking only unique errors.
| Name | Type |
|---|---|
error | Error |
void
services/error-tracking/errorTracking.service.ts:16
▸ trackGoal(goalId, conversionValue, dimensions?): void
Tracks manual goal conversion
| Name | Type |
|---|---|
goalId | string | number |
conversionValue | number |
dimensions? | Dimensions |
void
services/goal-conversions/goal-conversions.service.ts:8
▸ trackPageView(customPageTitle?): void
Tracks a visit on the page that the function was run on
| Name | Type |
|---|---|
customPageTitle? | string |
void
services/pageViews/pageViews.service.ts:7
▸ trackSiteSearch(keyword, category?, searchCount?, dimensions?): void
Tracks search requests on a website
| Name | Type |
|---|---|
keyword | string |
category? | string |
searchCount? | number |
dimensions? | Dimensions |
void
services/site-search/site-search.service.ts:8
▸ getUserId(): Promise<string>
The function that will return user ID
Promise<string>
services/user-management/userManagement.service.ts:9
▸ getVisitorId(): Promise<string>
Returns 16-character hex ID of the visitor
Promise<string>
services/user-management/userManagement.service.ts:44
▸ getVisitorInfo(): Promise<VisitorInfo>
Returns visitor information in an array
Promise<VisitorInfo>
services/user-management/userManagement.service.ts:63
▸ resetUserId(): void
Clears previously set userID, e.g. when visitor logs out
void
services/user-management/userManagement.service.ts:37
▸ setUserId(userId): void
User ID is an additional parameter that allows you to aggregate data. When set up, you will be able to search through sessions by this parameter, filter reports through it or create Multi attribution reports using User ID
| Name | Type |
|---|---|
userId | string |
void
services/user-management/userManagement.service.ts:30
▸ addEcommerceItem(productSKU, productName, productCategory, productPrice, productQuantity): void
| Name | Type |
|---|---|
productSKU | string |
productName | string |
productCategory | string | string[] |
productPrice | number |
productQuantity | number |
void
Deprecated
Please use the ecommerceAddToCart instead.
services/e-commerce/e-commerce.service.ts:14
▸ clearEcommerceCart(): void
void
Deprecated
services/e-commerce/e-commerce.service.ts:130
▸ ecommerceAddToCart(products): void
Tracks action of adding products to a cart
| Name | Type |
|---|---|
products | Product[] |
void
services/e-commerce/e-commerce.service.ts:34
▸ ecommerceCartUpdate(products, grandTotal): void
Tracks current state of a cart
| Name | Type |
|---|---|
products | Product[] |
grandTotal | string | number |
void
services/e-commerce/e-commerce.service.ts:113
▸ ecommerceOrder(products, paymentInformation): void
Tracks conversion, including products and payment details
| Name | Type |
|---|---|
products | Product[] |
paymentInformation | PaymentInformation |
void
services/e-commerce/e-commerce.service.ts:96
▸ ecommerceProductDetailView(products): void
Tracks action of viewing product page
| Name | Type |
|---|---|
products | Product[] |
void
services/e-commerce/e-commerce.service.ts:123
▸ ecommerceRemoveFromCart(products): void
Tracks action of removing a products from a cart
| Name | Type |
|---|---|
products | Product[] |
void
services/e-commerce/e-commerce.service.ts:48
▸ getEcommerceItems(): Promise<object>
Promise<object>
Deprecated
services/e-commerce/e-commerce.service.ts:55
▸ removeEcommerceItem(productSKU): void
| Name | Type |
|---|---|
productSKU | string |
void
Deprecated
Please use the ecommerceRemoveFromCart instead.
services/e-commerce/e-commerce.service.ts:41
▸ setEcommerceView(productSKU, productName?, productCategory?, productPrice?): void
| Name | Type |
|---|---|
productSKU | string |
productName? | string |
productCategory? | string[] |
productPrice? | string |
void
Deprecated
services/e-commerce/e-commerce.service.ts:137
▸ trackEcommerceCartUpdate(cartAmount): void
| Name | Type |
|---|---|
cartAmount | number |
void
Deprecated
Please use the ecommerceCartUpdate instead.
services/e-commerce/e-commerce.service.ts:106
▸ trackEcommerceOrder(orderId, orderGrandTotal, orderSubTotal?, orderTax?, orderShipping?, orderDiscount?): void
| Name | Type |
|---|---|
orderId | string |
orderGrandTotal | number |
orderSubTotal? | number |
orderTax? | number |
orderShipping? | number |
orderDiscount? | number |
void
Deprecated
Please use the ecommerceOrder instead.
FAQs
Piwik PRO basic tracking library for the frontend.
The npm package @piwikpro/tracking-base-library receives a total of 1,076 weekly downloads. As such, @piwikpro/tracking-base-library popularity was classified as popular.
We found that @piwikpro/tracking-base-library demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.